home *** CD-ROM | disk | FTP | other *** search
/ BBS in a Box 15 / BBS in a box XV-2.iso / Files II / Prog / T / The Journal.sit / The Journal / README FIRST
Encoding:
Text File  |  1991-03-16  |  7.7 KB  |  161 lines  |  [TEXT/KAHL]
  1. Welcome to 'The Journal'. This file describes how to use The Journal,
  2. and gives an introduction to the source code that comes with it.
  3.  
  4. All of the code is written in ThinkC (4.0.4). The only code that is
  5. not provided is that used for displaying the INITs icon at startup.
  6. This code was taken from
  7.     The Macintosh Programming Primer Volume II:
  8.         Mastering the Toolbox using Think C
  9.     by Dave Mark
  10.     Addison-Wesley, 1990 (ISBN 0-201-57016-5)
  11.     
  12. The program and source is in the public domain. It is totally free.
  13. You do not have the right to charge for it. If you use it in you own
  14. programs, please acknowledge the source. If you make changes, please let
  15. me know.
  16.  
  17. What does The Journal Do:
  18. =========================
  19.  
  20. The Macintosh is an event driven machine. Every time the user types a key,
  21. chooses a menu item, or clicks the mouse an event is generated. This event
  22. is read by the currently active application (or the Finder) and some kind
  23. of action results.
  24.  
  25. In the course of my studies, I found that I needed something that captured
  26. what the user did on the keyboard. Although macro packages and screen recording
  27. programs caught a lot of user events, they did not catch the mistakes. What if the
  28. user pressed the wrong key ? I needed a program that caught all events, and attached
  29. a time stamp to them.
  30.  
  31. This is what The Journal does. It captures most events (see How Does It Do It below)
  32. that occur at the keyboard or the mouse (or even disk insertions). These are recorded
  33. to a file. Granted, the formatting could be better. But what do you expect for a not
  34. quite first version ?
  35.  
  36.  
  37. How to Use The Journal:
  38. =======================
  39.  
  40. To use The Journal drag it into your system folder and reboot your machine.
  41. Next open up your control panel. IMPORTANT: Hold down the Option key when you
  42. select the Control Panel from the Apple menu. If you do not, The Journal will
  43. only record a few events.
  44.  
  45. Once you have selected The Journal in the control panel, you can do a couple
  46. of things. First, you can change the type of file that The Journal creates.
  47. By default, the file will be a Microsoft Word text file. To change the application
  48. used to read the text file, hit the 'Set Journal File Type' button. You will be given
  49. a typical open dialog, select an application that can read text files. Unfortunately,
  50. the 'Current Creator' will not reflect the change until you re-select The Journal in
  51. the Control Panel (sighh).
  52.  
  53. You can also specify if you want time stamps in the journal file. The default is to
  54. have no time stamps. If you want them, simply click the 'Time Stamps' checkbox.
  55. Adding time stamps will roughly double the size of the file created.
  56.  
  57. So far, you can not start the driver going. To do that you must first specify a file
  58. to write to. Do this using the 'Set Journal File' button. You will get a standard
  59. Macintosh save file dialog box. If you hit OK, the 'Start' button will be enabled.
  60.  
  61. To start the journaling, hit the 'Start' button. You can only do this if you have
  62. picked a file to journal too. Once you press this button, the journaling commences.
  63. Notice that other buttons dim out, and the name of the 'Start' button changes to 'Stop'.
  64. To stop journaling, hit the 'Stop' button.
  65.  
  66. You can close the Control Panel if you wish. It will not effect the journaling process.
  67.  
  68. WARNING: The Journal uses the same method of catching events as MacroMaker. If you use
  69. MacroMaker, it will muck up The Journal, and vice versa. The Journal is NOT compatible
  70. with MacroMaker.
  71.  
  72.  
  73. This archive should contain the following folders and files:
  74. ============================================================
  75.  
  76. README FIRST        - this file
  77.  
  78. cdev                - folder for the cdev project
  79.     The Journal                - the actual journal driver cdev/INIT/DRVR combination
  80.     Journal cdev π            - the journal cdev project
  81.     Journal cdev π.rsrc        - the resources for the cdev project (see notes below)
  82.     Journal cdev.c            - C source for the journal cdev object
  83.     Journal cdev.h            - header file for the journal cdev object
  84.     
  85. install DRVR INIT    - folder for the installer INIT project
  86.     driver.c                - the code that does all the work of installing (not mine)
  87.     driver.h                - include file for driver.c (not mine)
  88.     installJournalDriver.c    - code to call the installation routine
  89.     installJournalDriver.h    - the header file for installJournalDriver.c
  90.     Journal INIT            - a compiled version of the INIT
  91.     Journal INIT.π            - the install INIT project
  92.     Journal INIT.π.rsrc        - resources for the INIT project
  93.     
  94. journal Driver        - folder for the driver project
  95.     Journal Driver            - a compiled version of the driver (see notes below)
  96.     Journal Driver.π        - the project for the journal driver
  97.     journalDriver.c            - C code for the journal driver (and lots of it)
  98.     journalDriver.h            - header file for the journal driver
  99.     journalDriverInclude.h    - shared header file for communication with the driver
  100.  
  101. How Does It Do It:
  102. ==================
  103.  
  104. The Macintosh Event Manager contains something called the Journaling Mechanism. You can
  105. set up a driver that will get called every time the active application calls GetNextEvent,
  106. WaitNextEvent, EventAvail, and a few other calls. The Journal uses the Journaling 
  107. Mechanism to trap events as the application makes the event calls.
  108.  
  109. That means a couple of things. First, since MacroMaker also uses the Journaling Mechanism,
  110. it will conflict with The Journal. Second, if Applications do things in a stupid way,
  111. The Journal will reflect that. For example, Microsoft Word makes three calls for every
  112. keypress (why, how should I know !). That means every keystroke in typing is recorded
  113. three times ! TTThhhaaattt iiisss rrreeeaaalllyyy ddduuummmbbb !!! But what can you do.
  114.  
  115. Notes On Compiling The Journal:
  116. ===============================
  117.  
  118. If you are going to use the code, you need to know how to build the final project.
  119. The file 'Journal cdev π.rsrc' contains all the resources for the cdev, plus all
  120. of the resources from the other two projects. That means if you make changes to
  121. either the INIT or the DRVR, you have to build those components, then copy the
  122. resulting resources (DRVR, INIT, or whatever you add) to the 'Journal cdev π.rsrc'
  123. file BEFORE you build the final integrated cdev/INIT/DRVR.
  124.  
  125. Also, if you rebuild the DRVR, it is EXTREEMLY important to change the resource
  126. flags of both the DRVR and the DATA resource. They should both be 'System Heap' and
  127. 'Locked'. If not, The Journal WILL NOT WORK. And changing the attributes in the INIT
  128. does NOT help.
  129.  
  130. How to Contact Me (and what I can do):
  131. ======================================
  132.  
  133. First of all a disclaimer. This is NOT a commercial product. I do not guarenttee it in
  134. any way, manner, shape, or form. If it does something nasty to you, it is on your head.
  135. I also am not committed to supporting this program. I am releasing it because other
  136. researchers may find it useful. And other programmers can get saved the troubles of
  137. figuring out how to do things.
  138.  
  139. I do intend to make some changes to The Journal. It needs a lot of cleaning up and
  140. a fair bit of documenting. There are also other features I want to add, like picking
  141. up the name of an icon that is clicked on, getting the file that is chosen from
  142. a dialog, and a few others.
  143.  
  144. As to how to contact me. I am currently completing my MsC at the University of Calgary.
  145. I am likely to be out of there by May (though they are likely to know where to find me).
  146. However, the University is NOT a phone service. You can send mail to me there, but do NOT
  147. phone the office, they will NOT give out my number, or forward messages. They have
  148. enough to do already. Also, do NOT phone me at home (unless you want to offer me a job !).
  149. Feel free to email or smail (snail mail) me. I will respond to everything at some point.
  150.  
  151. Maurice Sharp
  152. Knowledge Science Lab
  153. Department of Computer Science
  154. University of Calgary
  155. 2500 University Dr. N.W.
  156. Calgary, AB
  157. Canada
  158. T2N 1N4
  159.  
  160. Internet: sharp@cpsc.ucalgary.ca  GEnie: M.SHARP5
  161.